Version: 4.2.x

Upgrade from XDK4.0 to XDK4.1

This release covers many small things that the Accedo developers have reported on the #group-js, focusing all the effort on the developer experience and performance.

Please read all the points carefully with the changes you will need to apply to your projects.

Installing XDK 4.1 dependencies

npm i \
  @accedo/xdk-config@~4.1.0 \
  @accedo/xdk-core@~4.1.0 \
  @accedo/xdk-log@~4.1.0

danger

XDK 4 may introduce breaking changes when upgrading the minor semver number.

Please use the ~ instead of the standard ^ to avoid any updates when the minor number is updated.

List of changes done in 4.1:

Moved device files out of the core into module `@accedo/xdk-base-modules`.

We have moved all the device-related classes from the core to a new package: @accedo/xdk-base-modules, so you also need to install it, together with @accedo/xdk-core and @accedo/xdk-config, @accedo/xdk-log and any other XDK dependency that you have.

If your projects were using any device-related class, besides the Interfaces and Abstracts one, please update the code as follows:

+  import { device, util, Environment, SystemConstants } from '@accedo/xdk-core';
+  import { HTML5System, MouseOnOff } from '@accedo/xdk-base-modules';
-  import { device, util, Environment, HTML5System, MouseOnOff, SystemConstants } from '@accedo/xdk-core';

In case your project uses vKey from @accedo/xdk-core, you will also need to update it:

+  import { .., ... } from '@accedo/xdk-core';
+  import { vKey } from '@accedo/xdk-base-modules';
-  import { ..., vKey, ... } from '@accedo/xdk-core';

Changes on `xdk.config.js`

We have fixed the next common xdk.config.js issues:

devices.details attribute is no longer mandatory
devices.details[PLATFORM].cookieName is no longer mandatory, as it defaults to a internal name

We have also added two new attributes to the exported object to help with the configuration of the cookie storage global name and the possibility of overriding the guessProtocolByUrl for some edge cases where the default strategy is returning the wrong protocol.

xdk.config.js
...
 // Storages configurations
  storages: {
    cookie: {
      name: 'vanilla-xdk-app'
    }
  },
  // Media configurations
  media: {
    // eslint-disable-next-line no-unused-vars
    guessProtocolByUrl: (url, options) => {
      for (const [key, regexpFn] of Object.entries(PROTOCOL_REGEX)) {
        if (regexpFn().test(url)) {
          return PROTOCOL[key];
        }
      }

      return PROTOCOL.PROGRESSIVE;
    }
  },
  ...

Added new storages.cookie.name attribute to define a global cookie name
Added ne media.guessProtocolByUrl function to override the default guess function

Changes on `@accedo/xdk-config` module

tip

This section is useful only if you are not importing the xdk-device packages from the artifactory.

If you do not have defined any device within your repo you should jump to Changes on @accedo/xdk-device-... exports section

Now the @accedo/xdk-config module exports a DeviceConfig model used to wrap each @accedo/xdk-device... configuration, extending it with some practical helper functions like .addPlayer(), .forceDetection() or .addExtension().

In the following example, you will find how to wrap your configuration to get the advantage of the brand new helpers.

xdk.config.js
+import { DeviceConfig } from '@accedo/xdk-config';

const devices = {
  packages: [
+     // Create a new instance of the Device Config model wrapping the current configuration    
+     new DeviceConfig({
        id: 'android-webview',
        detection: () =>
          __USE_ESM__
            ? import(`@accedo/xdk-device-android-webview/esm/detection.js`)
            : import(`@accedo/xdk-device-android-webview/cjs/detection.js`),
        defaultConfig: () =>
          __USE_ESM__
            ? import(`@accedo/xdk-device-android-webview/esm/defaultConfig.js`)
            : import(`@accedo/xdk-device-android-webview/cjs/defaultConfig.js`),
        DevicePackage: () =>
          __USE_ESM__
            ? import(`@accedo/xdk-device-android-webview/esm/DevicePackage.js`)
            : import(`@accedo/xdk-device-android-webview/cjs/DevicePackage.js`)
        },
+     )
+     // now we have the new helper methods available
+     .addPlayer(player)

In the following example, you will see all the available methods. Please visit the JSDoc page to check how to use the methods.

xdk.config.js
// other imports, like inMemory Storage, networkConfig, shaka and hls players...
import { DeviceConfig } from '@accedo/xdk-config';
import { ttsConfig, inmemoryStorage, networkConfig, detection, shaka, hlsjs } from 'many_modules';

const CONFIG = {
  devices: {
    new DeviceConfig({
      // config here
    })
      .addExtension(ttsConfig)
      .addStorage(inMemoryStorage)
      .replaceNetwork(networkConfig)
      .overrideDetection(detection)
      .overrideDetection(failDetection)
      .forceDetection(true)
      .addPlayer(shaka, {
        // shaka config
      })
      .addPlayer(hlsjs, {
        // hlsjs config
      })
  }
};

Changes on `@accedo/xdk-device-...` exports

On XDK 4.1, we have included the device config into each device package, and we export it along with the platform ID.

The exported configuration is an instance of the @accedo/xdk-config DeviceConfig model, providing the new helper functions.

@accedo/xdk-device-xxx
import { DeviceConfig } from '@accedo/xdk-config';
import ID from './id';

const xdkDeviceWorkstation = {
  id: ID,
  detection: () => import('./detection.js'),
  defaultConfig: () => import('./defaultConfig.js'),
  DevicePackage: () => import('./DevicePackage.js')
};

export default new DeviceConfig(xdkDeviceWorkstation);

The new approach simplifies the xdk.config.js as in most cases, you will only need to import the config and pass it to the configuration.

All the @accedo/xdk-device-... packages now exports their ID and configuration, as you will see in the following example:

+ import android  from '@accedo/xdk-device-android-webview';
+ import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
+ const devices = {
+   packages: [
+     android
+     workstation
+   ],
+   default: {
+     [WORKSTATION]: [
+       // here your modules
+     ],
+ }
- const devices = {
-   packages: [{
-       id: 'android-webview',
-       detection: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-android-webview/esm/detection.js`)
-           : import(`@accedo/xdk-device-android-webview/cjs/detection.js`),
-       defaultConfig: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-android-webview/esm/defaultConfig.js`)
-           : import(`@accedo/xdk-device-android-webview/cjs/defaultConfig.js`),
-       DevicePackage: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-android-webview/esm/DevicePackage.js`)
-           : import(`@accedo/xdk-device-android-webview/cjs/DevicePackage.js`)
-     },
-     {
-       id: 'workstation',
-       detection: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-workstation/esm/detection.js`)
-           : import(`@accedo/xdk-device-workstation/cjs/detection.js`),
-       defaultConfig: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-workstation/esm/defaultConfig.js`)
-           : import(`@accedo/xdk-device-workstation/cjs/defaultConfig.js`),
-       DevicePackage: () =>
-         __USE_ESM__
-           ? import(`@accedo/xdk-device-workstation/esm/DevicePackage.js`)
-           : import(`@accedo/xdk-device-workstation/cjs/DevicePackage.js`)
-      },
-   },
-   default: {
-     "workstation": [
-       // here your overrides
-     ]
-   }
- }
-

Added new module `@accedo/xdk-extensions-contrib` with Text To Speech

We have included the TTS modules for Vizio, LG Webos and HTML5 based devices, and the extension can add them to our devices with the .addExtension() method.

xdk.config.js
import { tts }  from '@accedo/xdk-extensions-contrib';
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation';

const { html5: html5TtsConfig, vizio: vizioTtsConfig  } = tts;

const CONFIG = {
  devices: {
    packages: [
      workstation
        .addExtension(html5TtsConfig)
    ] 
  }
}

app.js
import { tts }  from '@accedo/xdk-extensions-contrib';

const { ID: TTS  } = tts;

const tts = await xdk.extensionManager.getExtension(TTS);
tts.speak('awesome!');

Added new module `@accedo/xdk-players-contrib` with hls.jsj and shaka player

We have included a couple of standard players to add to our platforms on the xdk.config.js file.

xdk.config.js
import { shaka, hlsjs } from '@accedo/xdk-players-contrib'
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation';
const CONFIG = {
  devices: {
    packages: [
      workstation
        .addPlayer(shaka, {
          'streaming.bufferingGoal': 120
        })
        .addPlayer(hls, {
          nudgeMaxRetry: 6
        })
    ] 
  }
}

Resulting simplified `xdk.config.js` file

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
import playstationMsdk  from '@accedo/xdk-device-playstation-msdk';

import { tts }  from '@accedo/xdk-extensions-contrib'
import { shaka, hlsjs } from '@accedo/xdk-players-contrib'

const { html5: html5TtsConfig, vizio: vizioTtsConfig  } = tts;

export default {
  devices: {
    packages: [
      playstationMsdk,
      workstation
        .addExtension(html5TtsConfig)
        .forceDetection(true)
        .addPlayer(shaka, {
          'streaming.bufferingGoal': 120
        })
        .addPlayer(hls, {
          nudgeMaxRetry: 6
        })
    ],
    // details now is optional
    details: {
      [WORKSTATION]: {
        // overrides here
      }
    }
  }
  storages: {
    // cookie.name global cookie name
  },
  media: {
    // media gessProtocolByUrl function
  },
  logging: {
    // logging options
  }
};

Player changes. New interface `getPlayerObject` method

After reviewing some projects, we've realised that under some circumstances, it's quite common to require the player object for many reasons, including

Usage of 3rd party libs like analytics or ads handling
Requirement of listening to extra or native events/errors
Configure the player with custom options

To help with those requirements, we have exposed the getPlayerObject from XDK media.

caution

Some player object may not be HTML5 \<video> tags, be careful with the returned object.

app.js
// Using shaka
const shaka = xdk.media.getPlayerObject();
shaka.getMediaElement(); // returns the attached video tag

Player changes multiple configuration entry points

We have also implemented a mechanism to pass our custom configuration to the players following the next priority

On application side with xdk.media.load('url',{config: {}})
On configuration side with platform.addPlayer(player, config)
On playerConfig definition with the config: {} object

This way, we will use our handles in a standard way for most of our players.

app.js
// using hls.js
const tokenHook = () => {
  // logic to handle a mandatory token for the stream chunks
});

xdk.media.load('url', {
  config: {
    // any hls.js config attribute

    // a real example from hotmart 
    xhrSetup: (xhr, url) => {        
      url = `${url}${tokenHook()}`;

      return xhr.open('GET',url, true);        
    }
});

Remember that we can set the configuration from the player config or the addPlayer(player, {}) method over a device on the xdk.config.js file.

Removed exports from `@accedo/xdk-core`

Removed from @accedo/xdk-core
- ajax, promise and thennable
- Removed utils
- Removed constant utils List of removed utils:
areArraysEqual
areObjectsEqual
argumentsNames
bind
breaker
camelize
clear
clearDelay
contains
decamelize
decodeHTML
defer
delay
each
encodeHTML
every
filter
find
findIndex
first
flatten
has
indexOf
insert
inspect
isArguments
isDate
isDOMElement
isFinite
isNaN
keys
last
lastIndexOf
map
methodize
parse
pick
pluck
reduce
reduceRight
remove
stringify
shuffle
size
some
sort
sortByField
sortByFields
startsWith
strip
truncate
values
wrap

and also some of the Constant Utils:

createEnumeration
deepFreeze
freeze
toLowerSpinalCase

Please replace any of the above utilities with ES standard methods or polyfills.

Upgrade from XDK4.0 to XDK4.1

Installing XDK 4.1 dependencies​

danger

List of changes done in 4.1:​

Moved device files out of the core into module @accedo/xdk-base-modules.​

Changes on xdk.config.js​

Changes on @accedo/xdk-config module​

tip

Changes on @accedo/xdk-device-... exports​

Added new module @accedo/xdk-extensions-contrib with Text To Speech​

Added new module @accedo/xdk-players-contrib with hls.jsj and shaka player​

Resulting simplified xdk.config.js file​

Player changes. New interface getPlayerObject method​

caution

Player changes multiple configuration entry points​

Removed exports from @accedo/xdk-core​

Installing XDK 4.1 dependencies

List of changes done in 4.1:

Moved device files out of the core into module `@accedo/xdk-base-modules`.

Changes on `xdk.config.js`

Changes on `@accedo/xdk-config` module

Changes on `@accedo/xdk-device-...` exports

Added new module `@accedo/xdk-extensions-contrib` with Text To Speech

Added new module `@accedo/xdk-players-contrib` with hls.jsj and shaka player

Resulting simplified `xdk.config.js` file

Player changes. New interface `getPlayerObject` method

Player changes multiple configuration entry points

Removed exports from `@accedo/xdk-core`